表記揺れを治すために表記統一リストを作成して、textlint で検知・修正する

表記揺れを治すために表記統一リストを作成して、textlint で検知・修正する

#Classmethod Cloud Guidebook
#textlint
川原征大

川原征大

facebook logohatena logotwitter logo
Clock Icon2024.10.25

社内のエンジニアチームにてナレッジサイト(Classmethod Cloud Guidebook[1])を運営しています。

sc_2024-10-10_08-22-49_17830
ナレッジサイト(Classmethod Cloud Guidebook)

おおよそ2年ほど継続して追記・更新しており、 ドキュメント量も増えてきました。 また、複数人(=社内のエンジニア)が関わる環境なので、 人によって書きっぷりも異なってきます。

$ cat docs/**/*.md | wc -lm
   13061  446458
# ↑ ナレッジサイトの総ページは 1万行以上、40万文字以上

sc_2024-10-25_10-24-44_5513
社内リポジトリのコントリビューター数は41人(2024/10/25時点)

もともと textlint 自体による自動校正は導入していました(参考)。 技術文書向けのルールセット(preset-ja-technical-writing)を活用して、 ある程度の品質は担保されていました。

しかし、細かい表記揺れは校正できていませんでした。 たとえば すべき/するべき といった語尾の表現や サーバ/サーバー などのカタカナ表記などです。 その他にも CMメンバーズ/クラスメソッドメンバーズ といった専門用語の表記揺れもありました。

そういった背景があり、よりドキュメントの品質を上げるべく 表記統一リスト を作成しました。 それをベースに、 textlint の各種ルールを 活用して表記揺れを検知・修正する仕組みを作ってみます。

計画の概要

実施した内容は以下のとおりです。それぞれ順番に説明していきます。

  1. 表記揺れのカテゴリ を決める
  2. 表記揺れを洗い出して 表記統一リスト を作成する
  3. 表記統一リストを基に textlint による検知・修正の仕組み を作る

1. 表記揺れのカテゴリを決める

表記統一リストを今後メンテナンスしやすくするために、 表記揺れを以下8つにカテゴリ分けしました。

  1. 語尾や接続表現
  2. 漢字とひらがな
  3. カタカナ表記
  4. 送り仮名
  5. 数字や全角/半角
  6. 英字・カタカナ
  7. 略語
  8. 専門用語

語尾や接続表現

代表的なものは「ですます調/である調」の表記揺れです。 ほかにも「すべき/するべき」や 「することができます/できます」といった言い回しの表記揺れが対象です。

これらは文章の印象に与える影響が大きいため、統一する価値がある部分です。

漢字とひらがな

「おこなう/行う」や「ください/下さい」などは 表記揺れが特に発生しやすいです。

読みやすさに重きをおいて統一ルールを作成していきます。

カタカナ表記

外来語のカタカナ表記も表記揺れが多いです。 「サーバー/サーバ」や「ユーザー/ユーザ」などです。

送り仮名

「取り扱い/取扱い」、「割り当て/割当て」といった 送り仮名を省略されうるものは統一ルールを作成する価値があります。

数字や全角/半角

数字の表現も「ひとつ/1つ/１つ/一つ」というように さまざまな表記があります。

また、括弧の表現も「 全角の括弧 （） 」 と「 半角の括弧 () 」 で、 どちらを使うか分かれるところです。

英字・カタカナ

英字で書くか、カタカナで書くかの表記揺れになります。 たとえば「DBインスタンス/データベースインスタンス」、 「web ACL/ウェブACL」などです。

略語

「マネジメントコンソール/マネコン」や「オンプレミス/オンプレ」 などの良く使われる略語について、統一ルールを作成します。

専門用語

AWSサービスの正式名称や 自社のサービスの名称は 統一する価値がある部分です。

AWSサービスを正式名称で記載することはもちろん、 自社サービスの表記(「クラスメソッドメンバーズ/CMメンバーズ」など) を統一するためのルールを定めます。

2. 表記統一リストを作成する

先ほど決めたカテゴリごとに 表記揺れをどんどん洗い出していきます。 「望ましくない表記 → 望ましい表記」のテーブルを作成していきます。

sc_2024-10-25_14-28-52_12345
表記統一リスト

洗い出しにあたって実施したことを紹介していきます。

  • 執筆メンバーで洗い出し
  • textlint 同義語チェックの活用
  • 生成AIの活用

執筆メンバーで洗い出し

社内のメンバー間でドキュメントを読み合わせながら、 表記揺れを洗い出していきます。 素朴な方法ですが重要です。

厳しすぎるルールは、逆に執筆の足かせになりえます。 普段よく執筆しているメンバーの意見を集めながら、表記統一リストを作成していきます。

textlint 同義語チェックの活用

textlint の textlint-rule-no-synonyms は、 文章中の同義語表記揺れをチェックできる便利なルールです。 同義語の辞書として Sudachi 同義語辞書 が使われています。

既存のドキュメントにこのチェックを走らせて、同義語を洗い出します。

# ドキュメントを1ファイルにまとめる
cat ./docs/**/*.md > ./tmp_all.md
# textlint-rule-no-synonyms ルールでチェック(導入部分は割愛)
npx textlint --rule @textlint-ja/no-synonyms ./tmp_all.md

以下出力サンプルです。

~/ccg/docs/tmp_all.md
   525:33  error  同義語である「および」と「及び」が利用されています                      @textlint-ja/no-synonyms
  1709:23  error  同義語である「割り当て」と「割当」が利用されています                    @textlint-ja/no-synonyms
  1714:38  error  同義語である「サーバー」と「サーバ」が利用されています                  @textlint-ja/no-synonyms
  3518:29  error  同義語である「パラメータ」と「パラメーター」が利用されています          @textlint-ja/no-synonyms
  4067:29  error  同義語である「漏洩」と「漏えい」が利用されています                      @textlint-ja/no-synonyms
  5023:34  error  同義語である「クラスター」と「クラスタ」が利用されています              @textlint-ja/no-synonyms
  5032:51  error  同義語である「繋がり」と「つながり」が利用されています                  @textlint-ja/no-synonyms
  ...(略)

生成AIの活用

さらに生成AIも活用して表記揺れを洗い出しました。 ツールとしては、自社の 生成AI環境構築サービスである「 AI-Starter 」を活用しました。

https://classmethod.jp/services/generative-ai/ai-starter/

以下のようなプロンプトを何度も走らせて、表記揺れを見つけます。 アシスタントとしては Claude 3.5 Sonnet v2 を使いました。

あなたは文章校正のエキスパートです。

添付したドキュメントを注意深く読んでください。
ドキュメントのクオリティに影響するような表記揺れを見つけてリスト化してください。

リストは以下に示す適切なカテゴリに分けて出力してください。

- 語尾や接続表現
- 漢字とひらがな
- カタカナ表記
- 送り仮名
- 数字や全角/半角
- ローマ字・カタカナ
- 略語
- 専門用語

sc_2024-10-25_14-55-58_8452

以下のようにいい感じに洗い出してくれます。

sc_2024-10-25_15-04-48_24524

ただしドキュメント内にはそもそも無い表記揺れがあったり、 許容されるような表記揺れ(+ そもそも表記揺れではなさそうなもの)も多くありました。

そのため、最終的には人の判断で表記統一リストに反映させます。

3. textlintによる検知・修正の仕組みを作る

表記統一リストをベースに textlint ルールを実装していきます。 主に以下ルールを活用していく予定です。

それぞれ説明していきます。

AWS用語は aws-service-name ルールを活用

https://dev.classmethod.jp/articles/create_aws_textlint_rule/

上記ブログで紹介されている aws-service-name ルールを使って、 AWSサービス名の表記揺れを検出できます。 AWSに関するドキュメントを扱っているのでとても重宝しています。

ですます調の統一は no-mix-dearu-desumasu ルールを活用

https://github.com/textlint-ja/textlint-rule-no-mix-dearu-desumasu

ですます調は no-mix-dearu-desumasu ルールを適用するのが便利です。

そのほかは prh ルールを活用

https://github.com/textlint-rule/textlint-rule-prh

そのほかの表記揺れは textlint-rule-prh を使って対応できないか検討します。 このルールは校正を手伝ってくれるライブラリである proofreading-helper(prh) を textlint プラグインとしたものです。

以下のように表記統一リストの内容を prh.yml として記載します。

prh.yml(抜粋)
version: 1
rules:
  ### 語尾や接続表現
  - expected: すべき
    pattern:
      - するべき

  ### 漢字とひらがな
  - expected: おこなう
    pattern:
      - 行う
      - 行なう
  - expected: すべて
    pattern:
      - 全て
  - expected: および
    pattern:
      - 及び

  ### カタカナ表記・外来語
  - expected: ユーザー
    pattern:  /ユーザ(?!ー)/
  - expected: サーバー
    pattern:  /サーバ(?!ー)/
  - expected: レイヤー
    pattern:  /レイヤ(?!ー)/

  ### 送り仮名
  - expected: 取り扱い
    pattern: 取扱い
  - expected: 割り当て
    pattern: 割当て

  ### 数字や全角・半角
  - expected: ひとつ
    pattern:
      - 一つ
      - 1つ

  ### 英字・カタカナ
  - expected: "web ACL"
    pattern:
      - "ウェブACL"
      - "ウェブ ACL"

  ### 略語
  - expected: オンプレミス
    pattern:  /オンプレ(?!ミス)/
    specs:
      - from: オンプレ
        to: オンプレミス
      - from: オンプレミス
        to: オンプレミス

  ### 専門用語
  - expected: "クラスメソッドメンバーズ"
    pattern:
      - "CMメンバーズ"

prh.yml をベースに検知・修正できるように textlint 設定を更新します。

{
  "rules": {
    "prh": {
      "rulePaths": [
        "./prh.yml"
      ]
    }
  }
}

以下出力例です。

$ npx textlint ./docs/SecurityHubGuide/AFSBP.md
~/ccg/docs/SecurityHubGuide/AFSBP.md
   # ...略
   525:33   ✓ error  及び => および                prh
   # ...略
   620:43   ✓ error  漏洩 => 漏えい                prh
   664:20   ✓ error  下さい => ください            prh
   # ...略
   727:43   ✓ error  サーバ => サーバー            prh
   728:8    ✓ error  サーバ => サーバー            prh
   731:30   ✓ error  下さい => ください            prh
   733:19   ✓ error  下さい => ください            prh
   # ...略
   887:33   ✓ error  サーバ => サーバー            prh
   890:76   ✓ error  するべき => すべき            prh

おわりに

表記揺れ解消プロセスのサンプルでした。

表記揺れを解消するには表記統一リストを作成して チームメンバーに浸透させる必要があります。 また、自動化できる部分はどんどん自動化したいです。 自動化には textlint が役に立ちます。

以上、参考になれば幸いです。

参考

https://kagurazaka-editors.jp/unified-notation/

https://github.com/textlint-rule/textlint-rule-prh

https://classmethod.jp/services/generative-ai/ai-starter/

脚注

  1. Classmethod Cloud Guidebook(CCG)は クラスメソッドメンバーズ(請求代行サービス)向けに公開している ナレッジサイトです。お客様のクラウド推進を支援すべく、AWSのセキュリティや統制、ガイドライン周りで役立つナレッジを公開しています。詳細は こちらのブログ を参照ください。 ↩︎

Share this article

facebook logohatena logotwitter logo

関連記事

いちナレッジサイトにおける MkDocs および Material for MkDocs の 設定まとめ【静的サイトジェネレータ】

いちナレッジサイトにおける MkDocs および Material for MkDocs の 設定まとめ【静的サイトジェネレータ】

User avatar
川原征大
2024.10.10
「組織的AWS活用のススメ」というタイトルで登壇しました #cm_odyssey

「組織的AWS活用のススメ」というタイトルで登壇しました #cm_odyssey

User avatar
たかやま
2024.07.30
Classmethod Cloud Guidebook のアップデート紹介(2024年上半期分)

Classmethod Cloud Guidebook のアップデート紹介(2024年上半期分)

User avatar
川原征大
2024.07.19
『〜AWS初心者向け〜　 ベストプラクティスから学ぶ 「AWSセキュリティの高め方」』というタイトルで登壇しました

『〜AWS初心者向け〜　 ベストプラクティスから学ぶ 「AWSセキュリティの高め方」』というタイトルで登壇しました

User avatar
こーへい
2024.06.03
Classmethod's white logo
Facebook's logo
X's logo
YouTube's logo

© Classmethod, Inc. All rights reserved.